<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>AngelScript: Your first script</title>

<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>


</head>
<body>
<div id="top"><!-- do not remove this div! -->


<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">AngelScript
   
   </div>
   
  </td>
  
  
  
   
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.5.1 -->
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
  initNavTree('doc_hello_world.html','');
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">Your first script </div>  </div>
</div>
<div class="contents">
<div class="textblock"><p>This tutorial will show you the basics on how to configure the engine, compile a script, and then execute it.</p>
<p>In this tutorial a couple of add-ons are used to make the code easier. You are not required to use these in your own application, but they will most likely let you get your project up and running faster. You'll want to take a look at the rest of the <a class="el" href="doc_addon.html">add-ons</a> later on to see what else may be useful for you.</p>
<div class="fragment"><pre class="fragment"><span class="comment">// Include the definitions of the script library and the add-ons we&#39;ll use.</span>
<span class="comment">// The project settings may need to be configured to let the compiler where</span>
<span class="comment">// to find these headers. Don&#39;t forget to add the source modules for the</span>
<span class="comment">// add-ons to your project as well so that they will be compiled into the </span>
<span class="comment">// application.</span>
<span class="preprocessor">#include &lt;<a class="code" href="angelscript_8h.html" title="The API definition for AngelScript.">angelscript.h</a>&gt;</span>
<span class="preprocessor">#include &lt;scriptstdstring/scriptstdstring.h&gt;</span>
<span class="preprocessor">#include &lt;scriptbuilder/scriptbuilder.h&gt;</span>
</pre></div><p>Being an embedded scripting library there isn't much that AngelScript allows the scripts to do by themselves, so the first thing the application must do is to <a class="el" href="doc_register_api.html">register the interface</a> that the script will have to interact with the application. The interface may consist of functions, variables, and even complete classes.</p>
<p>Pay special attention to how the <a class="el" href="doc_compile_script.html#doc_compile_script_msg">message callback</a> is registered right after the engine is created. The message callback is used by the engine to give human readable error messages when something isn't working as it should, e.g. a registration is done incorrectly, or a script has an error that fails to compile. While you still need to verify the return codes, the message callback can give you valuable information that will let you figure out what is wrong without much effort.</p>
<div class="fragment"><pre class="fragment"><span class="comment">// Create the script engine</span>
<a class="code" href="classas_i_script_engine.html" title="The engine interface.">asIScriptEngine</a> *engine = <a class="code" href="angelscript_8h.html#af84c6359750675bf3ceccf373286a533" title="Creates the script engine.">asCreateScriptEngine</a>(<a class="code" href="angelscript_8h.html#a99c6b8b0882e45e5d0b2ed19f6f7a157">ANGELSCRIPT_VERSION</a>);

<span class="comment">// Set the message callback to receive information on errors in human readable form.</span>
r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a74192fe950808eb72a64e3e371f0ea02" title="Sets a message callback that will receive compiler messages.">SetMessageCallback</a>(<a class="code" href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae" title="Returns an asSFuncPtr representing the function specified by the name.">asFUNCTION</a>(MessageCallback), 0, <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4a68ae43cc91cdfc3fa4590c9e6164e4f4" title="A cdecl function.">asCALL_CDECL</a>); assert( r &gt;= 0 );

<span class="comment">// AngelScript doesn&#39;t have a built-in string type, as there is no definite standard </span>
<span class="comment">// string type for C++ applications. Every developer is free to register it&#39;s own string type.</span>
<span class="comment">// The SDK do however provide a standard add-on for registering a string type, so it&#39;s not</span>
<span class="comment">// necessary to implement the registration yourself if you don&#39;t want to.</span>
RegisterStdString(engine);

<span class="comment">// Register the function that we want the scripts to call </span>
r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a754fafd069d8e0c19baff2dc222893b0" title="Registers a global function.">RegisterGlobalFunction</a>(<span class="stringliteral">&quot;void print(const string &amp;in)&quot;</span>, <a class="code" href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae" title="Returns an asSFuncPtr representing the function specified by the name.">asFUNCTION</a>(print), <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4a68ae43cc91cdfc3fa4590c9e6164e4f4" title="A cdecl function.">asCALL_CDECL</a>); assert( r &gt;= 0 );
</pre></div><p>After the engine has been configured, the next step is to compile the scripts that should be executed.</p>
<p>The following is our script that will call the registered <code>print</code> function to write <code>Hello world</code> on the standard output stream. Let's say it's stored in the file <code>test.as</code>.</p>
<pre>
  void main()
  {
    print("Hello world\n");
  }
</pre><p>Here's the code for loading the script file and compiling it. The AngelScript engine itself doesn't have access to the filesystem so the loading the files has to be done by the application. Here we're going to use the <a class="el" href="doc_addon_build.html">script builder</a> add-on, which does the loading of the script files, and some preprocessing, such as handling #include directives.</p>
<div class="fragment"><pre class="fragment"><span class="comment">// The CScriptBuilder helper is an add-on that loads the file,</span>
<span class="comment">// performs a pre-processing pass if necessary, and then tells</span>
<span class="comment">// the engine to build a script module.</span>
CScriptBuilder builder;
r = builder.StartNewModule(engine, <span class="stringliteral">&quot;MyModule&quot;</span>); 
<span class="keywordflow">if</span>( r &lt; 0 ) 
{
  <span class="comment">// If the code fails here it is usually because there</span>
  <span class="comment">// is no more memory to allocate the module</span>
  printf(<span class="stringliteral">&quot;Unrecoverable error while starting a new module.\n&quot;</span>);
  <span class="keywordflow">return</span>;
}
r = builder.AddSectionFromFile(<span class="stringliteral">&quot;test.as&quot;</span>);
<span class="keywordflow">if</span>( r &lt; 0 )
{
  <span class="comment">// The builder wasn&#39;t able to load the file. Maybe the file</span>
  <span class="comment">// has been removed, or the wrong name was given, or some</span>
  <span class="comment">// preprocessing commands are incorrectly written.</span>
  printf(<span class="stringliteral">&quot;Please correct the errors in the script and try again.\n&quot;</span>);
  <span class="keywordflow">return</span>;
}
r = builder.BuildModule();
<span class="keywordflow">if</span>( r &lt; 0 )
{
  <span class="comment">// An error occurred. Instruct the script writer to fix the </span>
  <span class="comment">// compilation errors that were listed in the output stream.</span>
  printf(<span class="stringliteral">&quot;Please correct the errors in the script and try again.\n&quot;</span>);
  <span class="keywordflow">return</span>;
}
</pre></div><p>The last step is to identify the function that is to be called, and set up a context for executing it.</p>
<div class="fragment"><pre class="fragment"><span class="comment">// Find the function that is to be called. </span>
<a class="code" href="classas_i_script_module.html" title="The interface to the script modules.">asIScriptModule</a> *mod = engine-&gt;<a class="code" href="classas_i_script_engine.html#a9f7cdc52b59034e6e55eb8a56b427aa4" title="Return an interface pointer to the module.">GetModule</a>(<span class="stringliteral">&quot;MyModule&quot;</span>);
<a class="code" href="classas_i_script_function.html" title="The interface for a script function description.">asIScriptFunction</a> *func = mod-&gt;<a class="code" href="classas_i_script_module.html#ab4754d55d8667aefbed135b4794d461b" title="Returns the function by its declaration.">GetFunctionByDecl</a>(<span class="stringliteral">&quot;void main()&quot;</span>);
<span class="keywordflow">if</span>( func == 0 )
{
  <span class="comment">// The function couldn&#39;t be found. Instruct the script writer</span>
  <span class="comment">// to include the expected function in the script.</span>
  printf(<span class="stringliteral">&quot;The script must have the function &#39;void main()&#39;. Please add it and try again.\n&quot;</span>);
  <span class="keywordflow">return</span>;
}

<span class="comment">// Create our context, prepare it, and then execute</span>
<a class="code" href="classas_i_script_context.html" title="The interface to the virtual machine.">asIScriptContext</a> *ctx = engine-&gt;<a class="code" href="classas_i_script_engine.html#a2630e1cd03ffab0fee9b820bf0afe42a" title="Creates a new script context.">CreateContext</a>();
ctx-&gt;<a class="code" href="classas_i_script_context.html#a43976f42dfc6c1af23e132d36265173a" title="Prepares the context for execution of the function.">Prepare</a>(func);
r = ctx-&gt;<a class="code" href="classas_i_script_context.html#a8e52894432737acac2e1a422e496bf84" title="Executes the prepared function.">Execute</a>();
<span class="keywordflow">if</span>( r != <a class="code" href="angelscript_8h.html#a867f14b4137dd4602fda1e616b217a69a6d3730dd7a91aff81cafaaca4e93efaa" title="The context has successfully completed the execution.">asEXECUTION_FINISHED</a> )
{
  <span class="comment">// The execution didn&#39;t complete as expected. Determine what happened.</span>
  <span class="keywordflow">if</span>( r == <a class="code" href="angelscript_8h.html#a867f14b4137dd4602fda1e616b217a69aa3d548fa7d2278d848e50222b700c6c8" title="The execution was terminated by an unhandled script exception.">asEXECUTION_EXCEPTION</a> )
  {
    <span class="comment">// An exception occurred, let the script writer know what happened so it can be corrected.</span>
    printf(<span class="stringliteral">&quot;An exception &#39;%s&#39; occurred. Please correct the code and try again.\n&quot;</span>, ctx-&gt;<a class="code" href="classas_i_script_context.html#a46e2411bc84e99f57e7d9fe2374bb479" title="Returns the exception string text.">GetExceptionString</a>());
  }
}
</pre></div><p>The exception handling above is very basic. The application may also obtain information about line number, function, call stack, and even values of local and global variables if wanted.</p>
<p>Don't forget to clean up after you're done with the engine.</p>
<div class="fragment"><pre class="fragment"><span class="comment">// Clean up</span>
ctx-&gt;<a class="code" href="classas_i_script_context.html#a1b13a5f3e58627e9ff4300c0c6f0f3cf" title="Decrease reference counter.">Release</a>();
engine-&gt;<a class="code" href="classas_i_script_engine.html#aae91a45da75af9234b87e825b5c08b81" title="Decrease reference counter.">Release</a>();
</pre></div><h2><a class="anchor" id="doc_hello_world_1"></a>
Helper functions</h2>
<p>The print function is implemented as a very simple wrapper on the printf function.</p>
<div class="fragment"><pre class="fragment"><span class="comment">// Print the script string to the standard output stream</span>
<span class="keywordtype">void</span> print(<span class="keywordtype">string</span> &amp;msg)
{
  printf(<span class="stringliteral">&quot;%s&quot;</span>, msg.c_str());
}
</pre></div><dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="doc_compile_script.html#doc_compile_script_msg">Message callback</a>, <a class="el" href="doc_addon_build.html">Script builder</a>, and <a class="el" href="doc_addon_std_string.html">string object</a> </dd></dl>
</div></div>
</div>
  <div id="nav-path" class="navpath">
    <ul>

    <li class="footer">Generated on Sun Jan 29 2012 15:41:04 for AngelScript by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.5.1 </li>
   </ul>
 </div>


</body>
</html>
